/*
 * Sii Commons
 *
 * Copyright (c) 2011 Sii Sp. z o.o. All rights reserved.
 */
package pl.edu.pw.polygen.db.dao.generic;

import java.util.List;
import java.util.Map;

/**
 * Generic Data Access Object with most common CRUD methods. Extend this
 * interface if you want typesafe DAO's for your domain objects.
 * 
 * @param <T> persistent type class
 * @param <PK> primary key for the persistent type
 * 
 * @author Jakub Ciechan
 * @author Wojciech Kochman
 * @author Radosław Ryś
 * @version 1.2
 */
public interface GenericDao<T, PK extends java.io.Serializable> {

    /**
     * Generic method to persist an object.
     * 
     * @param object - the object to save
     * @return primary key assigned to the persisted object
     */
    PK save(T object);

    /**
     * Save changes made to an already persisted object.
     * 
     * @param object - object to update
     */
    void update(T object);

    /**
     * Saves or updates given object depending on its current state.
     * 
     * @param object - object to save or update
     */
    void saveOrUpdate(T object);

    /**
     * Convenience method to delete an object based on its id.
     * 
     * @param id - identifier (primary key) of the object to delete
     */
    void delete(PK id);

    /**
     * Permanently deletes the object from persistent storage.
     * 
     * @param object - object to delete
     */
    void delete(T object);

    /**
     * Retrieves an object based on its primary key identifier.
     * 
     * @param id - identifier (primary key) of the object to retrieve
     * @return populated object
     */
    T getById(PK id);

    /**
     * Convenience method to check if an object with a specified primary key
     * identifier exists.
     * 
     * @param id - identifier (primary key) of the object
     * @return - true if it exists, false if it doesn't
     */
    boolean exists(PK id);

    /**
     * Generic method used to get all objects of a particular type.
     * 
     * @return List of populated objects
     */
    List<T> getAll();

    /**

    /**
     * Retrieves a list of objects based on a query.
     * 
     * @param query - query to use
     * @return List of objects found
     */
    List<T> findByQuery(String query);

    /**
     * Retrieves a list of objects based on a named query.
     * 
     * @param queryName - query name of the named query
     * @param queryParams - a map of the query parameter names and the values
     * @return List of objects found
     */
    List<T> findByNamedQuery(String queryName, Map<String, Object> queryParams);

}
